home *** CD-ROM | disk | FTP | other *** search
/ BMUG PD-ROM 1995 Fall / PD-ROM F95.toast / Utilities / Printing / Print2Pict 3.0 ƒ / Sources / P2PX.h < prev    next >
Encoding:
C/C++ Source or Header  |  1992-05-26  |  14.5 KB  |  398 lines  |  [TEXT/ttxt]
  1. #define _H_P2PX
  2. /*==================================================================================
  3.  
  4. File P2PX.h 
  5. © B.Raoult 1992
  6.  
  7. mab@ecmwf.co.uk
  8.  
  9.  
  10. How to write a Print2Pict extension:
  11. ------------------------------------
  12.  
  13.     A Print2Pict extension is a code resource of type 'P2PX' id = -8192, 
  14. in a file of type 'P2PX' and creator 'P2P '. The code entry point is
  15. a Pascal function (so extension can be wrote in Pascal or C).  
  16.  
  17.     pascal  OSErr main(short msg,P2PXPtr arg);
  18.     
  19.     The function is called with two parameters: the first is a function selector,
  20. the second is a pointer to a parameter block containing various field described
  21. later. The function must return noErr if everything was OK, or the code
  22. of any errors.
  23.     
  24.     When the extension is called, the current resource file is set to the 
  25. extension file. 
  26.  
  27. Values of the message parameter:
  28. ================================                            
  29.      
  30. - getFlagsMsg
  31. -------------
  32.     
  33.     This message is sent before opening the Style or the Job dialogs:
  34.     Print2Pict use the answer to enable or disable some items in the
  35.     dialogs. You must fill the "flags" with the following values:
  36.     
  37.         if  ENVIRONMENT_OK is not set, the name of the extension is disabled in the
  38.         popup menu. It cannot be selected by the user. You must clear this bit
  39.         if your extension requires system features that are not available on this
  40.         machine. (Color QuickDraw, ...)
  41.         
  42.         
  43.         if WANT_FILE_NAMES is set, Print2Pict will generate a filename for every
  44.         page printed and pass it to you in the "fsspec" and "script" fields of
  45.         the argument when sending the putPageMsg message. This name either 
  46.         automatically generated or was specified by the user according to the
  47.         user choice in the Print2Pict options dialog. Use the "creator" field
  48.         to create the files. If you want only one file name, clear the 
  49.         WANT_FILE_NAMES bit once you have received the first putPageMsg message.
  50.         
  51.         if HAS_OWN_PAGE_SIZE is set, Print2Pict will look for a PREC resource
  52.         id = 3 in your resource file to setup the Style dialog. A maximum of
  53.         5 page sizes can be displayed (the sixth is reserved for the custom
  54.         paper size). When this bit is set, the external cannot be selected
  55.         in the Job dialog, as an other size may have been chosen in the Style
  56.         dialog.
  57.         
  58.         if HAS_OWN_OPTIONS is set, your external must provide a DITL resource
  59.         id = -8192, and ICON resource id = -8192 and optionally a cicn resource
  60.         id = -8192. The ICON (or cicn) is displayed in the options dialog.
  61.         If the user click on it, the DITL is then appended to the dialog. Your
  62.         external must respond to the optOpenMsg, optEventMsg, optItemMsg
  63.         and optDoneMsg messages.
  64.         
  65.         if ONLY_BLACK_WHITE is set, Print2Pict will create black and white picture.
  66.         
  67.         if CAN_PREVIEW is set the user can preview the pages before they are
  68.         disposed. If you provide a resource PREV id = -8192 containing a pascal
  69.         string that will be use to change the title of the disposition button in
  70.         the preview dialog.
  71.         
  72.         if CAN_SPOOL is set, Print2Pict may spool the picture to a file if the memory
  73.         is too low. The spooled field is set, spooledfile contains the filespec of
  74.         the spooled picture (PICT format). [NOT YET IMPLEMENTED]
  75.         
  76.     When entering your routine the "flags" field is set with the DEFAULT_FLAGS values
  77.     (ENVIRONMENT_OK + WANT_FILE_NAMES + CAN_PREVIEW).
  78.         
  79.     The getFlagsMsg message is also sent when the application calls PrOpenDoc,
  80.     before sending the initMsg, to check if the ENVIRONMENT_OK is still set.
  81.     
  82.     Don't use any fields of the argument other than the "flags" field.
  83.     
  84.     
  85.         
  86. - initMsg
  87. ---------
  88.  
  89.         The message is sent when the application calls PrOpenDoc. 
  90.         If you need some local storage, allocate a handle, and put it
  91.         in the "data" field of the argument.
  92.             
  93. - endMsg
  94. --------
  95.         The message is sent when the application calls PrCloseDoc.
  96.         You must free any memory allocated, close any opened file.
  97.         
  98.         Always check the "data" field before calling DisposHandle. 
  99.  
  100.  
  101. - putPageMsg
  102. ------------
  103.  
  104.         The message is sent when the application calls PrClosePage.
  105.         This is where you must process the picture.
  106.         
  107.         "error"        is the last error.
  108.         "page"      contains the current page number. (Starting from 1)
  109.         "pict"      contains a handle on the picture of the current page.
  110.         "docName"   is the name of the printed document (can be empty).
  111.         "appName"   is the name of the current application.
  112.         
  113.         If WANT_FILE_NAMES is set in the "flags" field: 
  114.         "fsspec"  is the file spec where the page is to be saved, and
  115.         "script"  the scriptcode to use with FSpCreate.
  116.  
  117.         If CAN_SPOLL is set in the "flags" field, Print2Pict may spool the
  118.         picture to disk if the memory is low. [NOT YET IMPLEMENTED]
  119.         "pict" is the set to NULL, "spooled" is true, and "spoolfile"
  120.         contains the file spec of the file where the picture is spooled
  121.         (PICT format) 
  122.             
  123.         
  124. - optOpenMsg
  125. ------------
  126.     
  127.         To receive this message the HAS_OWN_OPTIONS bit must be set.
  128.         Print2Pict display the DITL you provide and calls the external.
  129.         You can allocate some private storage in the "data" field.
  130.         You must initialize the dialog items here.
  131.         "dlog" is the dialog containing your items, "skip" is the number
  132.         of items in this dialog belonging to Print2Pict.
  133.         
  134. - optEventMsg
  135. -------------
  136.  
  137.         To receive this message the HAS_OWN_OPTIONS bit must be set.
  138.         The external is called from the ModalDialog filter procedure.
  139.         
  140.         "dlog" is the dialog containing your items, "skip" is the number
  141.         of items in this dialog belonging to Print2Pict.
  142.         "event" is the events that triggered the call, "itemHit" is the
  143.         item passed to the filter procedure, "retcode" must be set to 
  144.         true if "itemHit" was changed. See InsideMac I page 415 for
  145.         more details about the filter procedure.
  146.  
  147. - optItemMsg
  148. ------------
  149.  
  150.         To receive this message the HAS_OWN_OPTIONS bit must be set.
  151.         The external is called with the item returned by ModalDialog.
  152.         You must update the check boxes and the radio buttons.
  153.         "item" is the value return by ModalDialog.
  154.         "dlog" is the dialog containing your items, "skip" is the number
  155.         of items in this dialog belonging to Print2Pict.
  156.         The dialog item "skip" is a static text you can use to display
  157.         any messages.
  158.  
  159.  
  160. - optDoneMsg
  161. ------------
  162.  
  163.         To receive this message the HAS_OWN_OPTIONS bit must be set.
  164.         Print2Pict calls the external before removing the DITL from the dialog.
  165.         You must get the new values of the dialog items, and release any allocated
  166.         memory.
  167.         "dlog" is the dialog containing your items, "skip" is the number
  168.         of items in this dialog belonging to Print2Pict.
  169.  
  170.  
  171. Values of the P2PXPtr parameter:
  172. ================================     
  173.  
  174.     For every calls, a parameter is passed to the extension. All field are read only
  175. except "flags" and "data".
  176.  
  177.     Print2Pict fills the block with zeros and then sets the fields. So you are sure
  178. that missing fields are set to zero:
  179.  
  180.     ALWAYS CHECK A POINTER (OR HANDLE) FIELD AGAINST NULL BEFORE DEREFERENCING IT.                     
  181.      
  182.     This is a description of the field of the parameter block using the format
  183.     - name (type) [list of messages for which the field is valid]
  184.     
  185. - vers (short) [all]            
  186. --------------------        
  187.  
  188.     Print2Pict major version, set to 3 at present.
  189.     
  190. - port (TPPrPort) [putPageMsg]
  191. ------------------------------
  192.  
  193.     Current print graph port.
  194.     
  195. - hPrint (THPrint) [putPageMsg]
  196. -------------------------------
  197.  
  198.     Current print record.
  199.     
  200. - page (short) [putPageMsg]
  201. ---------------------------
  202.  
  203.     Current page number (starting from 1).
  204.     
  205. - pict (PicHandle) [putPageMsg]
  206. -------------------------------
  207.  
  208.     Picture of the current page. If NULL, then the picture was spooled (see
  209.     spooled and spoolfile)
  210.     
  211. - color (Boolean) [putPageMsg]
  212. ------------------------------
  213.  
  214.     Set to true if the print grafport is the color port.
  215.     
  216. - flags (long) [all]
  217. --------------------
  218.  
  219.     Set by the extension. See previous paragraph.
  220.  
  221. - error (OSErr) [all]
  222. --------------------
  223.  
  224.     Last error reported by Print2Pict.
  225.  
  226. - data (Handle) [initMsg,putPageMsg,endMsg]
  227.                 [optOpenMsg,optEventMsg,optItemMsg,optDoneMsg if HAS_OWN_OPTIONS]
  228. ---------------------------------------------------------------------------------
  229.  
  230.     Put here a handle to your private storage. Alocate it when
  231.     you receive initMsg or optOpenMsg, free it when you receive endMsg or optDoneMsg.
  232.  
  233. - docName (Str255) [initMsg,putPageMsg,endMsg]
  234. ----------------------------------------------
  235.  
  236.     Name of the printed document.
  237.     
  238. - appName (Str255) [initMsg,putPageMsg,endMsg]
  239. ----------------------------------------------
  240.  
  241.     Name of the current application.
  242.     
  243. - fspec (FSSpec) [putPageMsg if WANT_FILE_NAMES]
  244. ------------------------------------------------
  245.  
  246.     File spec. where to save the picture to.
  247.     
  248. - script (ScriptCode) [putPageMsg if WANT_FILE_NAMES]
  249. -----------------------------------------------------
  250.  
  251.     script code of fspec (needed for FSpCreate).
  252.     
  253. - creator (OSType) [all]
  254. ------------------------
  255.     
  256.     creator choosen by the user in the Print2Pict options dialog.
  257.  
  258. - spooled (Boolean) [putPageMsg if CAN_SPOLL] [NOT YET IMPLEMENTED]
  259. ------------------------------------------------------------------- 
  260.     
  261.     true if the picture was spooled.
  262.     
  263. - spoolfile (FSSpec) [putPageMsg if CAN_SPOLL] [NOT YET IMPLEMENTED]
  264. --------------------------------------------------------------------    
  265.     
  266.     file spec of the spooled picture (PICT file). set if spooled is true.
  267.     
  268. - dlog  (DialogPtr) [optOpenMsg,optEventMsg,optItemMsg,optDoneMsg if HAS_OWN_OPTIONS]
  269. -------------------------------------------------------------------------------------
  270.  
  271.     Dialog where the your DITL is displayed.
  272.  
  273. - event (EventRecord*) [optEventMsg if HAS_OWN_OPTIONS]
  274. -------------------------------------------------------
  275.  
  276.     Event received in ModalDialog filter procedure.
  277.  
  278. - itemHit (short*) [optEventMsg if HAS_OWN_OPTIONS]
  279. ---------------------------------------------------
  280.  
  281.     Item received in ModalDialog filter procedure.
  282.  
  283. - retcode (Boolean) [optEventMsg if HAS_OWN_OPTIONS]
  284. ----------------------------------------------------
  285.  
  286.     Return code of ModalDialog filter procedure.
  287.  
  288. - skip (short) [optOpenMsg,optEventMsg,optItemMsg,optDoneMsg if HAS_OWN_OPTIONS]
  289. --------------------------------------------------------------------------------
  290.  
  291.     Number of items belonging to Print2Pict in the dialog.
  292.  
  293. - item (short) [optItemMsg if HAS_OWN_OPTIONS]
  294. ----------------------------------------------
  295.     
  296.     Item number returned by ModalDialog.
  297.     
  298. Help:
  299. =====
  300.  
  301.     To provide somme help to the user, add a TEXT resource id = -8192 and
  302.     an optional styl resource, same id. The text will be displayed in the
  303.     Help window.
  304.     
  305. Ideas:
  306. ======    
  307.  
  308.     Here are some ideas of extensions:
  309.     - Print to Movie (QuickTime) each page is a frame.
  310.     - HyperPrint (HyperCard) each page is a card. Has its own paper format (the
  311.       size of a card.
  312.     - Print to RTF, Print to Word, ... all text formats.
  313.     - Print to PCX, GIF, all PC stuff, ....
  314.     - Print to X, XWindows Pixmaps.
  315.     
  316.     You are welcome to send me any extensions you write, so I can add them to 
  317.     the next releases of Print2Pict.
  318.  
  319.  
  320. ==================================================================================*/
  321.  
  322. #include <PrintTraps.h>
  323.  
  324.  
  325. /*============================ Messages =====================================*/
  326.  
  327. /* Get flags */
  328.  
  329. #define getFlagsMsg     1
  330.  
  331.  
  332. /* Printing ... */
  333.  
  334. #define initMsg         2
  335. #define endMsg          3
  336. #define putPageMsg      4
  337.  
  338. /* Options */
  339.  
  340. #define optOpenMsg      5
  341. #define optEventMsg     6
  342. #define optItemMsg      7
  343. #define optDoneMsg      8
  344.  
  345. /*=============================== Flags =====================================*/
  346.  
  347.  
  348. #define ENVIRONMENT_OK      1L  /* Set if machine OK (i.e. has color QD,...) */ 
  349. #define WANT_FILE_NAMES     2L  /* If code resource need file names          */
  350. #define HAS_OWN_PAGE_SIZE   4L  /* If the code has its own page size         */
  351. #define CAN_PREVIEW         8L  /* Pages can be previewed before disposed    */
  352. #define HAS_OWN_OPTIONS    16L  /* If code has own options dialog            */
  353. #define ONLY_BLACK_WHITE   32L  /* No color pictures                         */
  354. #define CAN_SPOOL          64L  /* Can use spooled pictures                  */
  355.  
  356. #define DEFAULT_FLAGS       (ENVIRONMENT_OK+WANT_FILE_NAMES+CAN_PREVIEW)
  357.  
  358. /*============================= Parameter block =============================*/
  359.  
  360. typedef struct {
  361.  
  362.     short       vers;       /* Print2Pict major version (3 now)          */
  363.     
  364.     TPPrPort    port;       /* Print graphport                           */
  365.  
  366.     THPrint     hPrint;     /* Print record                              */
  367.     short       page;       /* Current page                              */
  368.     PicHandle   pict;       /* Content of page                           */
  369.     Boolean     color;      /* The printport is a color port             */
  370.     
  371.     long        flags;      /* Code flags                                */
  372.     Handle      data;       /* Free to use                               */
  373.     
  374.     OSErr        error;        /* Last error code                           */
  375.     
  376.     Str255      docName;    /* Name of printed document                  */
  377.     Str255      appName;    /* Name of current application               */
  378.     
  379.     FSSpec      fspec;      /* File spec if WANT_FILE_NAMES              */
  380.     ScriptCode  script;     /* Script code if WANT_FILE_NAMES            */
  381.     OSType      creator;    /* user chosen creator                       */
  382.     
  383.     Boolean     spooled;    /* Picture was spooled                       */
  384.     FSSpec      spoolfile;  /* Spolled picture                           */
  385.     
  386.     /* Stuff for options dialog */
  387.     
  388.     DialogPtr   dlog;       /* The options dialog                        */
  389.     
  390.     EventRecord *event;     /* Event received in ModalDialog filter proc */
  391.     short       *itemHit;   /* Item received in ModalDialog filter proc  */
  392.     Boolean     retcode;    /* Retcode of ModalDialog filter proc        */
  393.     
  394.     short       skip;       /* Number of items belonging to Print2Pict   */
  395.     short       item;       /* Item number returned by modal dialog      */
  396.         
  397. } P2PXRec, *P2PXPtr;
  398.